Giới thiệu API FX Rate

Các API FX Rate cho phép Merchant tra cứu tỷ giá ngoại hối của Baokim theo thời gian thực, chuyển đổi số tiền giữa hai loại tiền tệ và truy vấn lịch sử tỷ giá.

Tỷ giá được trả về bởi các API này là một báo giá tham khảo cho Merchant yêu cầu. Ở giai đoạn hiện tại, báo giá chỉ dùng tham khảo và không cam kết giao dịch — việc khóa báo giá thành một thỏa thuận FX thực sẽ được xử lý ở giai đoạn sau. Mỗi báo giá đã có mã báo giá (quote_code) để có thể được đối chiếu và trong tương lai có thể được tái sử dụng để khóa tỷ giá.

1. Danh sách API

API	Endpoint	Method	Mục đích
Get Currencies	/cb-core/api/v1/fx/get-currencies	POST	Trả về danh sách các cặp tiền tệ mà Baokim có thể báo giá cho Merchant.
Get FX Rate	/cb-core/api/v1/fx/get-rate	POST	Lấy tỷ giá bid/ask cho một cặp, nhiều cặp hoặc tất cả các cặp được hỗ trợ.
Convert	/cb-core/api/v1/fx/convert	POST	Chuyển đổi số tiền giữa hai loại tiền tệ sử dụng tỷ giá hiện tại.
Get Historical Rate	/cb-core/api/v1/fx/get-historical-rate	POST	Truy vấn tỷ giá quá khứ của một cặp tiền tệ để đối chiếu và phân tích.

2. Xác thực

Các API FX Rate là một phần của dịch vụ Cross Border và sử dụng cùng một cơ chế ký request như các API Cross Border khác, được định nghĩa trong Giới thiệu API Baokim. Tóm gọn:

• Mỗi request được gửi dưới dạng body JSON được ký. Chữ ký được đặt trong header Signature và xác thực request cũng như đảm bảo tính toàn vẹn của dữ liệu.
• Ký sử dụng thuật toán RSA256 (SHA256withRSA). Cặp khóa RSA public/private được tạo bởi Merchant; private key được giữ trên phía Merchant và public key được chia sẻ với Baokim trong quá trình tích hợp.
• Baokim xác minh chữ ký bằng public key của Merchant. Chữ ký không hợp lệ sẽ bị từ chối với mã kết quả 120 Invalid Signature.

Header

Tên	Giá trị	Mô tả
Content-Type	application/json	Định dạng dữ liệu là JSON
Signature	Chữ ký số	Chữ ký số để xác thực request

Giá trị header Signature tuân theo định dạng được định nghĩa trong Giới thiệu API Baokim:

keyVersion=1.0,algorithm=RSA256,signature=base64-encoded-signature

3. Các trường Request chung

Mỗi FX Rate request chứa các trường sau ngoài các trường cụ thể cho từng API:

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
request_id	string(50)	Có	Mã duy nhất định danh request. Định dạng gợi ý: MerchantCode + BK + YYYYMMDD + UniqueId
request_time	string(19)	Có	Thời gian Merchant gửi request. Định dạng: YYYY-MM-DD HH:MM:SS
merchant_code	string(20)	Có	Mã merchant được định nghĩa trong hệ thống Baokim, được cung cấp cho Merchant trong quá trình tích hợp

4. Các trường Response chung

Tham số	Loại dữ liệu	Bắt buộc	Mô tả
response_code	int(4)	Có	Mã kết quả từ Baokim, theo bảng Mã lỗi
response_message	string(200)	Có	Mô tả mã kết quả, theo bảng Mã lỗi
merchant_code	string(20)	Có	Mã merchant được Baokim cung cấp trước khi tích hợp
data	Object/Array	Không	Payload cụ thể cho API. Vắng mặt hoặc null khi lỗi

Xem Mã lỗi để xem danh sách đầy đủ mã kết quả.

5. Bảng thuật ngữ

Thuật ngữ	Giải nghĩa
Currency pair	Một cặp được báo giá dưới dạng BASE/QUOTE, ví dụ USD/VND. Tiền tệ đầu tiên là ngoại tệ, tiền tệ thứ hai là VND.
bid	Tỷ giá mua — tỷ giá mà khách hàng bán ngoại tệ (nhập).
ask	Tỷ giá bán — tỷ giá mà khách hàng mua ngoại tệ (xuất).
spread	Chênh lệch ask - bid. Luôn bid < ask.
quote_code	Mã báo giá được trả về cùng với mỗi tỷ giá. Dùng để đối chiếu và dành cho khóa tỷ giá ở giai đoạn sau.
last_updated	Thời gian tỷ giá bị ảnh hưởng cuối cùng được làm mới (tính tươi của báo giá). Định dạng: YYYY-MM-DD HH:MM:SS
valid_until	Thời gian cho đến khi báo giá còn hiệu lực. Có thể null ở giai đoạn hiện tại.

6. Bid / Ask và Hướng

Tỷ giá luôn được trả về hai chiều (bid và ask) cho một cặp được báo giá dưới dạng BASE/QUOTE (ngoại tệ / VND).

Hành động khách hàng	Tỷ giá áp dụng	Ví dụ (USD/VND)
Khách hàng bán ngoại tệ	bid	USD → VND sử dụng bid
Khách hàng mua ngoại tệ	ask	VND → USD sử dụng ask

Trong API Convert, hướng được suy ra từ thứ tự của from_currency / to_currency: chuyển đổi ngoại tệ thành VND áp dụng bid, trong khi chuyển đổi VND thành ngoại tệ áp dụng ask. Phía được áp dụng được phản ánh trong response (rate_type).

7. Các cặp tiền tệ được hỗ trợ

• USD/VND luôn khả dụng.
• Các cặp khác (ví dụ CNY/VND) là tùy chọn và phụ thuộc vào ngân hàng nguồn thượng đạo và cấu hình của Merchant.
• Sử dụng Get Currencies để lấy các cặp thực sự có thể báo giá cho Merchant của bạn. Chỉ các cặp có thể báo giá một cách tin cậy mới được trả về.

8. Lưu ý quan trọng

• Giá theo Merchant: đối với cùng một cặp tiền tệ, các Merchant khác nhau có thể nhận được tỷ giá khác nhau tùy theo cấu hình/hợp đồng của họ.
• Không công khai nguồn: các API chỉ trả về các con số cuối cùng. Nguồn dữ liệu, công thức định giá và biên độ không bao giờ được công khai.
• Giới hạn tỷ lệ: mỗi Merchant bị giới hạn ở số lệnh gọi tối đa trên phút. Vượt quá giới hạn sẽ trả về lỗi "quá nhiều yêu cầu, vui lòng thử lại sau" (xem Mã lỗi).
• Khả năng truy tìm: mỗi request mang request_id của riêng nó, và mỗi báo giá mang quote_code của riêng nó.
• Chỉ tham khảo: ở giai đoạn hiện tại, báo giá là báo giá tham khảo và không phải cam kết. Nếu không có tỷ giá tin cậy khả dụng vào lúc yêu cầu, API sẽ trả về lỗi "FX rate not available".

9. Luồng tra cứu tỷ giá

Giai đoạn 1 — Thu thập tỷ giá định kỳ (nền, phía Baokim)

Bước	Diễn viên	Mô tả
1	Baokim	Thu thập tỷ giá từ (các) nguồn được cấu hình.
2	Baokim	Lưu trữ các tỷ giá cùng với last_updated.

Giai đoạn 2 — Merchant tra cứu tỷ giá

Bước	Diễn viên	Mô tả
1	Merchant	Gửi yêu cầu tỷ giá cho một cặp, nhiều cặp hoặc tất cả các cặp (tùy chọn có số tiền).
2	Baokim	Xác thực request và kiểm tra giới hạn tỷ lệ. Nếu vượt quá, trả về "thử lại sau".
3	Baokim	Đọc tỷ giá được lưu trữ. Nếu vẫn tươi, sử dụng trực tiếp; nếu không, làm mới từ nguồn.
4	Baokim	Nếu không thể làm mới tỷ giá, trả về "FX rate not available" và dừng.
5	Baokim	Áp dụng cấu hình giá của Merchant, tính toán bid/ask, tạo quote_code.
6	Baokim	Trả về bid/ask + quote_code + last_updated + valid_until.